什么是模型上下文协议 (MCP)？
模型上下文协议（Model Context Protocol，MCP） 是一种标准化协议，使 AI 模型能够以结构化的方式与外部工具和资源进行交互。可以将其视为 AI 模型与现实世界之间的桥梁——允许模型通过一致的接口访问数据库、API、文件系统和其他外部服务。它支持多种传输机制，以适应不同环境下的灵活性需求。
MCP Java SDK 提供了模型上下文协议的 Java 实现，支持通过同步和异步通信模式与 AI 模型及工具进行标准化交互。
Spring AI 通过专用的 Boot Starters 和 MCP Java 注解，全面拥抱 MCP，使得构建能够无缝连接外部系统的复杂 AI 驱动应用程序变得前所未有的简单。这意味着 Spring 开发者可以参与 MCP 生态系统的两端——构建消费 MCP 服务器的 AI 应用程序，以及创建向更广泛的 AI 社区暴露基于 Spring 的服务的 MCP 服务器。使用 Spring Initializer 快速启动带有 MCP 支持的 AI 应用程序。
Java MCP 架构
Java MCP 实现遵循三层架构，各层关注点分离，以确保可维护性和灵活性：
1. 客户端/服务器层（顶层）
顶层处理主要的应用程序逻辑和协议操作：
| 组件 | 说明 |
|---|---|
McpClient |
管理客户端操作和服务器连接 |
McpServer |
处理服务器端协议操作和客户端请求 |
这两个组件都利用下方的会话层进行通信管理。
2. 会话层（中间层）
中间层管理通信模式并维护连接状态：
| 组件 | 说明 |
|---|---|
McpSession |
核心会话管理接口 |
McpClientSession |
客户端特定的会话实现 |
McpServerSession |
服务器特定的会话实现 |
3. 传输层（底层）
底层处理实际的消息传输和序列化：
| 组件 | 说明 |
|---|---|
McpTransport |
管理 JSON-RPC 消息的序列化和反序列化 |
| 传输实现 | 支持多种传输实现（STDIO、HTTP/SSE、Streamable-HTTP 等） |
| 基础 | 为所有高层通信提供基础 |
MCP 客户端
MCP 客户端是模型上下文协议（MCP）架构中的关键组件，负责建立和管理与 MCP 服务器的连接。它实现了协议的客户端部分，处理以下事务：
- 协议版本协商：确保与服务器的兼容性
- 能力协商：确定可用的功能特性
- 消息传输和 JSON-RPC 通信
- 工具发现和执行
- 资源访问和管理
- 提示系统交互
可选功能
- Roots 管理
- 采样（Sampling）支持
- 同步和异步操作
传输选项
| 传输方式 | 说明 |
|---|---|
| Stdio | 基于标准输入/输出的进程间通信 |
| Java HttpClient SSE | 基于 Java HttpClient 的 SSE 客户端传输 |
| WebFlux SSE | 用于响应式 HTTP 流式的 WebFlux SSE 客户端传输 |
MCP 服务器
MCP 服务器是模型上下文协议（MCP）架构中的基础组件，向客户端提供工具、资源和能力。它实现了协议的服务器端，负责：
- 服务器端协议操作的实现
- 工具的暴露和发现
- 基于 URI 访问的资源管理
- 提示模板的提供和处理
- 与客户端的能力协商
- 结构化日志和通知
- 并发客户端连接管理
- 同步和异步 API 支持
传输实现
| 传输方式 | 说明 |
|---|---|
| Stdio | 标准输入/输出 |
| Streamable-HTTP | 可流式传输的 HTTP |
| Stateless Streamable-HTTP | 无状态可流式传输的 HTTP |
| SSE | 服务器发送事件 |
如需使用底层 MCP 客户端/服务器 API 的详细实现指南，请参阅 MCP Java SDK 文档。如需使用 Spring Boot 进行简化配置，请使用下文所述的 MCP Boot Starters。
Spring AI MCP Boot Starters
Spring AI 通过以下 Spring Boot Starters 提供 MCP 集成：
标准输入/输出 (STDIO)
| 服务器类型 | 依赖 | 属性配置 |
|---|---|---|
| STDIO | spring-ai-starter-mcp-server |
spring.ai.mcp.server.stdio=true |
WebMVC 传输
| 服务器类型 | 依赖 | 属性配置 |
|---|---|---|
| SSE WebMVC | spring-ai-starter-mcp-server-webmvc |
spring.ai.mcp.server.protocol=SSE 或留空 |
| Streamable-HTTP WebMVC | spring-ai-starter-mcp-server-webmvc |
spring.ai.mcp.server.protocol=STREAMABLE |
| Stateless Streamable-HTTP WebMVC | spring-ai-starter-mcp-server-webmvc |
spring.ai.mcp.server.protocol=STATELESS |
WebFlux 传输
| 服务器类型 | 依赖 | 属性配置 |
|---|---|---|
| SSE WebFlux | spring-ai-starter-mcp-server-webflux |
spring.ai.mcp.server.protocol=SSE 或留空 |
| Streamable-HTTP WebFlux | spring-ai-starter-mcp-server-webflux |
spring.ai.mcp.server.protocol=STREAMABLE |
| Stateless Streamable-HTTP WebFlux | spring-ai-starter-mcp-server-webflux |
spring.ai.mcp.server.protocol=STATELESS |
MCP 注解模块
除了编程式的 MCP 客户端和服务器配置外，Spring AI 还通过 MCP 注解模块 为 MCP 服务器和客户端提供基于注解的方法处理。这种方式使用简洁的声明式编程模型配合 Java 注解，简化了 MCP 操作的创建和注册。
MCP 注解模块使开发者能够：
- 使用简单的注解创建 MCP 工具、资源和提示
- 以声明式方式处理客户端通知和请求
- 减少样板代码，提高可维护性
- 自动生成工具参数的 JSON Schema
- 访问特殊参数和上下文信息
核心功能包括：
服务器端注解
| 注解 | 说明 |
|---|---|
@McpTool |
将方法暴露为 MCP 工具 |
@McpResource |
将方法暴露为 MCP 资源 |
@McpPrompt |
将方法暴露为 MCP 提示模板 |
@McpComplete |
为工具参数提供自动补全 |
客户端注解
| 注解 | 说明 |
|---|---|
@McpLogging |
处理日志通知 |
@McpSampling |
处理采样请求 |
@McpElicitation |
处理请求附加信息 |
@McpProgress |
处理进度通知 |
特殊参数
| 参数类型 | 说明 |
|---|---|
McpSyncServerExchange |
同步服务器交换上下文 |
McpAsyncServerExchange |
异步服务器交换上下文 |
McpTransportContext |
传输上下文信息 |
McpMeta |
元数据访问 |
其他特性
- 自动发现：支持可配置包包含/排除的注解扫描
- Spring Boot 集成：与 MCP Boot Starters 无缝集成
升级到 Spring AI 2.0
从 Spring AI 2.0 开始，Spring 特定的 MCP 传输实现（mcp-spring-webflux 和 mcp-spring-webmvc）不再由 MCP Java SDK 提供。它们已被移至 Spring AI 项目本身。这是一个破坏性变更，需要直接引用这些传输制品或类的应用程序更新依赖和导入。
Maven 依赖 Group ID 变更
mcp-spring-webflux 和 mcp-spring-webmvc 制品已从 io.modelcontextprotocol.sdk 组迁移至 org.springframework.ai。
迁移前（MCP Java SDK）：
1 | <dependency> |
迁移后（MCP Java SDK >= 1.0.x 且 Spring AI >= 2.0.x）：
1 | <dependency> |
当使用
spring-ai-bom或 Spring AI Starter 依赖（spring-ai-starter-mcp-server-webflux、spring-ai-starter-mcp-server-webmvc、spring-ai-starter-mcp-client-webflux）时，无需显式指定版本——BOM 会自动管理。
Java 包路径迁移
所有传输类已迁移至 org.springframework.ai 包下。
服务器传输类
| 类名 | 旧包路径 (MCP SDK) | 新包路径 (Spring AI) |
|---|---|---|
WebFluxSseServerTransportProvider |
io.modelcontextprotocol.server.transport |
org.springframework.ai.mcp.server.webflux.transport |
WebFluxStreamableServerTransportProvider |
io.modelcontextprotocol.server.transport |
org.springframework.ai.mcp.server.webflux.transport |
WebFluxStatelessServerTransport |
io.modelcontextprotocol.server.transport |
org.springframework.ai.mcp.server.webflux.transport |
WebMvcSseServerTransportProvider |
io.modelcontextprotocol.server.transport |
org.springframework.ai.mcp.server.webmvc.transport |
WebMvcStreamableServerTransportProvider |
io.modelcontextprotocol.server.transport |
org.springframework.ai.mcp.server.webmvc.transport |
WebMvcStatelessServerTransport |
io.modelcontextprotocol.server.transport |
org.springframework.ai.mcp.server.webmvc.transport |
客户端传输类
| 类名 | 旧包路径 (MCP SDK) | 新包路径 (Spring AI) |
|---|---|---|
WebFluxSseClientTransport |
io.modelcontextprotocol.client.transport |
org.springframework.ai.mcp.client.webflux.transport |
WebClientStreamableHttpTransport |
io.modelcontextprotocol.client.transport |
org.springframework.ai.mcp.client.webflux.transport |
导入示例更新
1 | // 迁移前 |
MCP SDK 版本要求
Spring AI 2.0 要求 MCP Java SDK 1.0.0（RC1 或更高版本）。SDK 版本已从 0.18.x 升级至 1.0.x 系列。请相应更新您的 BOM 或显式版本号。
Spring Boot 自动配置用户
如果您仅依赖通过 Spring AI Starters 进行的 Spring Boot 自动配置，则无需更改任何 Java 代码。自动配置已在内部更新为引用新包路径。只需按上述说明更新 pom.xml / build.gradle 中的依赖坐标即可。